<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <link rel="stylesheet" href="docgen-resources/docgen.css" type="text/css">
  <meta name="generator" content="FreeMarker Docgen (DocBook 5)">
  <title>
    FreeMarker Manual - Preface
  </title>
    <script type="text/javascript" src="docgen-resources/jquery.js"></script>
    <script type="text/javascript" src="docgen-resources/linktargetmarker.js"></script>
</head>
<body>

    <div class="navigation">
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          Preface
</span>    </div>
    <div class="bookmarks">
<span class="bookmarks">Bookmarks:
<a href="alphaidx.html">Alphabetical Index</a>, <a href="gloss.html">Glossary</a>, <a href="ref.html">Reference</a>, <a href="app_faq.html">FAQ</a>, <a href="api/index.html">Java API</a>, <a href="../index.html">FreeMarker Home</a></span>    </div>
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="dgui.html"><span class="hideA">Next page: </span>Template Author's Guide</a></div><div class="pagerButton"><a href="index.html">Previous page</a></div><div class="pagerButton"><a href="index.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    </div>

<div id="mainContent">

  
  
  
  
  <h1 class="rank_part"
        id="pageTopTitle">
<a name="preface"></a>Preface  </h1>
    
    <div class="toc">
      <p>
        <b>
            Page Contents
        </b>
      </p>
      
  <ul class="noMargin">
      <li>
        <a href="#autoid_2">What is FreeMarker?</a>
      </li>
      <li>
        <a href="#autoid_3">What should I read?</a>
      </li>
      <li>
        <a href="#autoid_4">Document conventions</a>
      </li>
      <li>
        <a href="#autoid_5">Contact</a>
      </li>
      <li>
        <a href="#autoid_6">About this document</a>
      </li>
  </ul>
    </div>
    <a name="docgen_afterTheTOC"></a>
    

        
  
  
  
  <h2 class="rank_section1"
        >
<a name="autoid_2"></a>What is FreeMarker?  </h2>


      <p>FreeMarker is a <i>template engine</i>: a generic
      tool to generate text output (anything from HTML to autogenerated source
      code) based on templates. It's a Java package, a class library for Java
      programmers. It's not an application for end-users in itself, but
      something that programmers can embed into their products.</p>

      <p>FreeMarker is designed to be practical for the generation of
      <i>HTML Web pages</i>, particularly by servlet-based
      applications following the <a href="gloss.html#gloss.MVC">MVC (Model View
      Controller) pattern</a>. The idea behind using the MVC pattern for
      dynamic Web pages is that you separate the designers (HTML authors) from
      the programmers. Everybody works on what they are good at. Designers can
      change the appearance of a page without programmers having to change or
      recompile code, because the application logic (Java programs) and page
      design (FreeMarker templates) are separated. Templates do not become
      polluted with complex program fragments. This separation is useful even
      for projects where the programmer and the HTML page author is the same
      person, since it helps to keep the application clear and easily
      maintainable.</p>

      <p>Although FreeMarker has some programming capabilities, it is
      <i>not</i> a full-blown programming language like PHP.
      Instead, Java programs prepare the data to be displayed (like issue SQL
      queries), and FreeMarker just generates textual pages that display the
      prepared data using templates.</p>

                <p align="center"><img src="figures/overview.png" alt="figure"></p>


      <p>FreeMarker is <i>not</i> a Web application
      framework. It is suitable as a component in a Web application framework,
      but the FreeMarker engine itself knows nothing about HTTP or servlets.
      It simply generates text. As such, it is perfectly usable in non-web
      application environments as well. Note, however, that we provide
      out-of-the-box solutions for using FreeMarker as the view component of
      Model 2 frameworks such as Struts.</p>

      <p>FreeMarker is <a href="http://www.fsf.org/philosophy/free-sw.html">Free</a>,
      released under a BSD-style license. It is <a href="http://www.opensource.org/">OSI Certified Open Source
      Software</a>. OSI Certified is a certification mark of the Open
      Source Initiative.</p>
    
        
  
  
  
  <h2 class="rank_section1"
        >
<a name="autoid_3"></a>What should I read?  </h2>


      <p>If you are a ...</p>

          <div class="itemizedlist">
<ul>
        <li>
          <p>designer, then you should read the <a href="dgui.html">Template Author's Guide</a> and
          then you can look into the <a href="ref.html">Reference</a> on an as-needed
          basis for more specific details.</p>
        </li>

        <li>
          <p>programmer, then you should read the <a href="dgui.html">Template Author's Guide</a>
          guide first, then the <a href="pgui.html">Programmer's Guide</a> and then you can look
          into the <a href="ref.html">Reference</a> on an as-needed basis for more
          specific details.</p>
        </li>
      </ul>    </div>

    
        
  
  
  
  <h2 class="rank_section1"
        >
<a name="autoid_4"></a>Document conventions  </h2>


      <p>Variable names, template fragments, Java class names, etc. are
      written like this: <tt style="color: #A03D10">foo</tt>.</p>

      <p>If something should be replaced with a concrete value then it is
      written in italics, as follows: <tt style="color: #A03D10">Hello
      <i style="color: #DD4400">yourName</i>!</tt>.</p>

      <p>Template examples are written like this:</p>

      <div align="left" class="programlisting"><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#D8D8D8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
something&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


      <p>Data-model examples are written like this:</p>

      <div align="left" class="programlisting"><table bgcolor="#99CCFF" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#99CCFF" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
something&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


      <p>Output examples are written like this:</p>

      <div align="left" class="programlisting"><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#CCFFCC" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
something&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


      <p>Program examples are written like this:</p>

      <div align="left" class="programlisting"><table bgcolor="#F8F8F8" cellspacing="0" cellpadding="0" border="0"><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td><table bgcolor="#F8F8F8" cellspacing="0" cellpadding="4" border="0" width="100%" style="margin: 0px"><tr><td><pre style="margin: 0px">
something&nbsp;<span style="font-size: 1pt"> </span></pre></td></tr></table></td><td width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td></tr><tr valign="top"><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td><td height="1" width="1" bgcolor="black"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></td>      </tr>
</table>  </div>


      

      <p>In chapters written for both designers and programmers fragments
      addressed to programmers are written like this: <span style="color:#333399; font-style:italic">This is for programmers only.</span></p>

      <p>New terms are emphasized like this: <b>some new
      term</b></p>
    
        
  
  
  
  <h2 class="rank_section1"
        >
<a name="autoid_5"></a>Contact  </h2>


      

      

      

      

      <p>For the latest version of FreeMarker and to subscribe to the
      <i>mailing lists</i> visit the FreeMarker homepage: <a href="http://freemarker.org/">http://freemarker.org</a></p>

      <p>If you <i>need help</i> or you have
      <i>suggestions</i>, use the mailing lists (mail archives
      can be searched without subscription) or the Web based forums. If you
      want to <i>report a bug</i>, use the Web based bug
      tracker, or the mailing lists. To find all of these visit <a href="http://freemarker.org/">http://freemarker.org</a>. Also,
      note that we have a <a href="app_faq.html">FAQ</a> and <a href="alphaidx.html">index</a>; use them.</p>
    
        
  
  
  
  <h2 class="rank_section1"
        >
<a name="autoid_6"></a>About this document  </h2>


      <p>If you find <i>any mistakes</i> (including
      <i>grammatical mistakes</i>, <i>typos</i>,
      typographical mistakes) or you find something <i>misleading or
      confusing</i> in the documentation, or you have other
      suggestions, please let me know! Email: ddekany at
      users.sourceforge.net</p>
      
</div>

    <div class="navigation">
    <div class="pagers">
      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
<div class="pagerButton"><a href="dgui.html"><span class="hideA">Next page: </span>Template Author's Guide</a></div><div class="pagerButton"><a href="index.html">Previous page</a></div><div class="pagerButton"><a href="index.html">Parent page</a></div><div class="pagerButton"><a href="index.html">Contents</a></div>      <div class="pagersVerticalSpacer"><img src="docgen-resources/img/none.gif" width="1" height="1" alt="" hspace="0" vspace="0" border="0"/></div>
    </div>
    <div class="breadcrumb">
<span class="breadcrumb">        You are here:
          <a href="index.html">Book</a>
            <b>></b>
          Preface
</span>    </div>
    </div>

<table border=0 cellspacing=0 cellpadding=0 width="100%">
    <tr>
      <td colspan=2><img src="docgen-resources/img/none.gif" width=1 height=8 alt=""></td>
    <tr>
      <td align="left" valign="top"><span class="smallFooter">
            FreeMarker Manual -- For FreeMarker 2.3.16
            <br>
          HTML generated: 2009-12-08 08:38:54 GMT
      </span></td>
      <td align="right" valign="top"><span class="smallFooter">
          <a href="http://www.xmlmind.com/xmleditor/">
            <img src="docgen-resources/img/xxe.gif" alt="Edited with XMLMind XML Editor">
          </a>
      </span></td>
    </tr>
</table>
  <!-- Put pre-loaded images here: -->
  <div style="display: none">
    <img src="docgen-resources/img/linktargetmarker.gif" alt="Here!" />
  </div>
</body>
</html>

